<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>NVTX C API Reference: NVTX C API Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">NVTX C API Reference<span id="projectnumber">&#160;v3</span>
   </div>
   <div id="projectbrief">NVIDIA Tools Extension Library</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">NVTX C API Reference </div></div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#INTRODUCTION">Introduction</a></li>
<li class="level1"><a href="#INITIALIZATION_SECTION">Initialization</a></li>
<li class="level1"><a href="#MARKERS_AND_RANGES">Markers and Ranges</a><ul><li class="level2"><a href="#MARKERS">Markers</a></li>
<li class="level2"><a href="#THREAD_RANGES">Thread Ranges</a></li>
<li class="level2"><a href="#PROCESS_RANGES">Process Ranges</a></li>
<li class="level2"><a href="#EVENT_ATTRIBUTES">Event Attributes</a></li>
</ul>
</li>
<li class="level1"><a href="#DOMAINS">Domains</a></li>
<li class="level1"><a href="#RESOURCE_NAMING">Resource Naming</a><ul><li class="level2"><a href="#CATEGORY_NAMING">Category Naming</a></li>
<li class="level2"><a href="#RESOURCE_OBJECTS">Resource Objects</a></li>
<li class="level2"><a href="#RESOURCE_NAMING_OS">Resource Naming</a></li>
</ul>
</li>
<li class="level1"><a href="#EXTENSIONS">Optional Extensions</a></li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="INTRODUCTION"></a>
Introduction</h1>
<p>The NVIDIA Tools Extension library is a set of functions that a developer can use to provide additional information to tools. The additional information is used by the tool to improve analysis and visualization of data.</p>
<p>The library introduces close to zero overhead if no tool is attached to the application. The overhead when a tool is attached is specific to the tool.</p>
<h1><a class="anchor" id="INITIALIZATION_SECTION"></a>
Initialization</h1>
<p>Typically the tool's library that plugs into NVTX is indirectly loaded via environmental properties that are platform specific. For some platform or special cases, the user may be required to instead explicitly initialize instead though. This can also be helpful to control when the API loads a tool's library instead of what would typically be the first function call to emit info. For these rare case, see INITIALIZATION for additional information.</p>
<h1><a class="anchor" id="MARKERS_AND_RANGES"></a>
Markers and Ranges</h1>
<p>Markers and ranges are used to describe events at a specific time (markers) or over a time span (ranges) during the execution of the application respectively.</p>
<h2><a class="anchor" id="MARKERS"></a>
Markers</h2>
<p>Markers denote specific moments in time.</p>
<p>See <a class="el" href="index.html#DOMAINS">Domains</a> and <a class="el" href="index.html#EVENT_ATTRIBUTES">Event Attributes</a> for additional information on how to specify the domain.</p>
<h2><a class="anchor" id="THREAD_RANGES"></a>
Thread Ranges</h2>
<p>Thread ranges denote nested time ranges. Nesting is maintained per thread per domain and does not require any additional correlation mechanism. The duration of a thread range is defined by the corresponding pair of nvtxRangePush* to nvtxRangePop API calls.</p>
<p>See <a class="el" href="index.html#DOMAINS">Domains</a> and <a class="el" href="index.html#EVENT_ATTRIBUTES">Event Attributes</a> for additional information on how to specify the domain.</p>
<h2><a class="anchor" id="PROCESS_RANGES"></a>
Process Ranges</h2>
<p>Process ranges denote a time span that can expose arbitrary concurrency, as opposed to thread ranges that only support nesting. In addition the range start event can happen on a different thread than the end marker. For the correlation of a start/end pair an unique correlation ID is used that is returned from the start API call and needs to be passed into the end API call.</p>
<h2><a class="anchor" id="EVENT_ATTRIBUTES"></a>
Event Attributes</h2>
<p><a class="el" href="index.html#MARKERS_AND_RANGES">Markers and Ranges</a> can be annotated with various attributes to provide additional information for an event or to guide the tool's visualization of the data. Each of the attributes is optional and if left unused the attributes fall back to a default value. The attributes include:</p><ul>
<li>color</li>
<li>category</li>
</ul>
<p>To specify any attribute other than the text message, the <a class="el" href="structnvtx_event_attributes__v2.html#EVENT_ATTRIBUTE_STRUCTURE">Event Attribute Structure</a> must be used.</p>
<h1><a class="anchor" id="DOMAINS"></a>
Domains</h1>
<p>Domains enable developers to scope annotations. By default all events and annotations are in the default domain. Additional domains can be registered. This allows developers to scope markers, ranges, and resources names to avoid conflicts.</p>
<p>The function <a class="el" href="group___d_o_m_a_i_n_s.html#ga2bbf44a48a4a46bf8900bd886524d87d" title="Register a NVTX domain.">nvtxDomainCreateA</a> or nvtxDomainCreateW is used to create a named domain.</p>
<p>Each domain maintains its own</p><ul>
<li>categories</li>
<li>thread range stacks</li>
<li>registered strings</li>
</ul>
<p>The function <a class="el" href="group___d_o_m_a_i_n_s.html#ga58b2508b5bbdfdd3cf30e4eaeb15a885" title="Unregister a NVTX domain.">nvtxDomainDestroy</a> marks the end of the domain. Destroying a domain unregisters and destroys all objects associated with it such as registered strings, resource objects, named categories, and started ranges.</p>
<h1><a class="anchor" id="RESOURCE_NAMING"></a>
Resource Naming</h1>
<p>This section covers calls that allow to annotate objects with user-provided names in order to allow for a better analysis of complex trace data. All of the functions take the handle or the ID of the object to name and the name. The functions can be called multiple times during the execution of an application, however, in that case it is implementation dependent which name will be reported by the tool.</p>
<h2><a class="anchor" id="CATEGORY_NAMING"></a>
Category Naming</h2>
<p>Some function in this library support associating an integer category to enable filtering and sorting. The category naming functions allow the application to associate a user friendly name with the integer category. Support for domains have been added in NVTX_VERSION_2 to avoid collisions when domains are developed independently.</p>
<h2><a class="anchor" id="RESOURCE_OBJECTS"></a>
Resource Objects</h2>
<p>Resource objects are a generic mechanism for attaching data to an application resource. The identifier field makes the association to a pointer or handle, while the type field helps provide deeper understanding of the identifier as well as enabling differentiation in cases where handles generated by different APIs may collide. The resource object may also have an associated message to associate with the application resource, enabling further annotation of this object and how it is used.</p>
<p>The resource object was introduced in NVTX_VERSION_2 to supersede existing naming functions and allow the application resource identified by those functions to be associated to a domain. The other naming functions are still supported for backward compatibility but will be associated only to the default domain.</p>
<h2><a class="anchor" id="RESOURCE_NAMING_OS"></a>
Resource Naming</h2>
<p>Some operating system resources creation APIs do not support providing a user friendly name, such as some OS thread creation APIs. This API support resource naming though both through resource objects and functions following the pattern nvtxName[RESOURCE_TYPE][A|W](identifier, name). Resource objects introduced in NVTX_VERSION 2 supersede the other functions with a a more general method of assigning names to OS resources, along with associating them to domains too. The older nvtxName* functions are only associated with the default domain. </p>
<h1><a class="anchor" id="EXTENSIONS"></a>
Optional Extensions</h1>
<p>Optional extensions will either appear within the existing sections the extend or appear in the "Related Pages" when they introduce new concepts. </p>
</div></div><!-- PageDoc -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8
</small></address>
</body>
</html>
